home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / XMSLB17.ARJ / XMSLIB.H < prev    next >
C/C++ Source or Header  |  1991-09-02  |  10KB  |  211 lines
  1. /*  Copyright 1990,1991 by Michael Graff.        USE AT YOUR OWN RISK       */
  2. /*              See end of this file for more information.                  */
  3. /*                                                                          */
  4. /*  Version 1.2, 08-Mar-91                                                  */
  5. /*  Version 1.3, 07-May-91                                                  */
  6. /*  Version 1.4, 27-May-91                                                  */
  7. /*  Version 1.5, 12-Jun-91    Fixed a few little errors                     */
  8. /*  Version 1.6, 02-Sep-91    Fixed one documentation error...              */
  9. /*  Version 1.7, 02-Sep-91    Reformatted a few comment lines only.         */
  10.  
  11. /* $Id: xmslib.h 1.7 91/09/02 12:17:11 explorer Exp Locker: explorer $ */
  12.  
  13. /*
  14.   $Log:    xmslib.h $
  15.  * Revision 1.7  91/09/02  12:17:11  explorer
  16.  * Changed a documentation error
  17.  * 
  18.  */
  19.  
  20. #include <dos.h>
  21.  
  22.     /*  The HMA can be used for data storage and code.                      */
  23.     /* This needs to be defined in ONE place in your code as:               */
  24.     /*    void far *HMAAddr = MK_FP(0xffff, 0x0010);                        */
  25.     /* and others as:                                                       */
  26.     /*  extern void far *HMAAddr;                                           */
  27.  
  28. typedef unsigned int XMShandle;
  29.  
  30. struct EMMMoveStruct {
  31.     unsigned long int   TransferLength;
  32.     XMShandle           SourceHandle;
  33.     unsigned long int   SourceOffset;
  34.     XMShandle           DestHandle;
  35.     unsigned long int   DestOffset;
  36. };  /*  Needed for the 640k to extended memory move routines                */
  37.  
  38. extern unsigned int far XMS_Setup(void);    /* MUST BE CALLED PRIOR TO      */
  39.                                             /* OTHER XMS_ ROUTINES!         */
  40.  
  41. extern unsigned char far XMS_FreeMem(   /* returns free and total extended  */
  42.          unsigned int far *freemem,     /* free extended memory in K        */
  43.          unsigned int far *totmem);     /* total extended memory in K       */
  44.  
  45. extern unsigned char far XMS_Version(   /* Returns version information      */
  46.          unsigned int far *version,     /* BCD protocol version (2.0)       */
  47.          unsigned int far *internal,    /* BCD internal version number      */
  48.          unsigned int far *HMA);        /* Does the HMA exist?              */
  49.  
  50. extern unsigned char far XMS_RequestHMA(    /* Try to allocate HMA          */
  51.          unsigned int mysize);  /* amount you'll be using in K.             */
  52.                                 /*  Applications should use 0xffff to       */
  53.                                 /*  allocate all 64k                        */
  54.  
  55. extern unsigned char far XMS_ReleaseHMA(void);  /* give up the HMA          */
  56.  
  57. extern unsigned char far XMS_GlobalEnableA20(void);  /* when the A20 line   */
  58. extern unsigned char far XMS_GlobalDisableA20(void); /* is enabled, the HMA */
  59. extern unsigned char far XMS_LocalEnableA20(void);   /* can be accessed.    */
  60. extern unsigned char far XMS_LocalDisableA20(void);
  61.  
  62. extern unsigned char far XMS_QueryA20(  /* Find out if A20 is enabled       */
  63.          unsigned int far *state);
  64.  
  65. extern unsigned char far XMS_AllocEMB(  /* Allocate extended momory         */
  66.          unsigned int mysize,           /* size in K needed                 */
  67.          XMShandle    far *handle);     /* handle for this EMB              */
  68.  
  69. extern unsigned char far XMS_FreeEMB(   /* Release an EMB                   */
  70.          XMShandle    handle);          /* handle to release                */
  71.  
  72. extern unsigned char far XMS_MoveEMB(       /* Move between real memory and */
  73.          struct EMMMoveStruct far *MoveRec);/* extended memory.             */
  74.  
  75. extern unsigned char far XMS_LockEMB(   /* make sure a memory block doesn't */
  76.          XMShandle    handle,           /* move.                            */
  77.          void far *address);    /* LINEAR memory address for this block     */
  78.  
  79. extern unsigned char far XMS_UnlockEMB( /* undo a lock                      */
  80.          XMShandle    handle);
  81.  
  82. extern unsigned char far XMS_GetEMBHandleInfo(   /* info on a handle        */
  83.          XMShandle    handle,               /* handle info wanted on        */
  84.          unsigned char far *LockCount,      /* number of locks enabled      */
  85.          unsigned char far *EMBHandlesFree, /* total handles free in system */
  86.          unsigned int far *EMBlength);      /* size of this handle in K     */
  87.  
  88. extern unsigned char far XMS_ReallocEMB(    /* Try to change the size of    */
  89.          XMShandle    handle,               /* this block.                  */
  90.          unsigned int newsize);             /* new size in K                */
  91.  
  92. extern unsigned char far XMS_RequestUMB(    /* request UPPER MEMORY BLOCK   */
  93.          unsigned int SizeWanded,           /* size in PARAGRAPHS needed    */
  94.          unsigned int far *segaddr,         /* segment address of block     */
  95.          unsigned int far *SizeUgot);       /* size of block you got        */
  96.  
  97. extern unsigned char far XMS_ReleaseUMB(    /* Release UMB                  */
  98.          unsigned int segaddr);
  99.  
  100. /*
  101. ------------------------------------------------------------------------------
  102.  
  103. If you find any errors, want to suggest improvements, or wish to use these
  104. routines in a commercial application, please write me at the following
  105. address:
  106.             Michael Graff
  107.             418 8th Avenue
  108.             Grinnell, IA  50112
  109.  
  110.             E-MAIL:  explorer@iastate.edu, ga.mlg@isumvs.bitnet
  111.  
  112.  
  113. You can use these routines for personal use without restrictions, other than
  114. I would like to get a copy of YOUR source.
  115.  
  116. If you use these routines in a program and make a profit, please share some
  117. small part of it with me!  (Donations of all kinds accepted, from very old
  118. hardware to old compact disks to a copy of part or all of your source to
  119. a thank you.)
  120.  
  121.  
  122. --Michael
  123.  
  124.  
  125. ------------------------------------------------------------------------------
  126.  
  127.  
  128. DEFINITIONS: ( stolen from the XMS 2.0 spec doc )
  129. -------------------------------------------------
  130.  
  131.     Extended
  132.     Memory      -   Memory in 80286 and 80386 based machines which is located
  133.                     above the 1MB address boundary.
  134.  
  135.     High Memory
  136.     Area (HMA)  -   The first 64K of extended memory.  The High Memory
  137.             Area is unique because code can be executed in it while
  138.             in real mode.  The HMA officially starts at FFFF:10h
  139.             and ends at FFFF:FFFFh making it 64K-16 bytes in length.
  140.  
  141.     Upper Memory
  142.     Blocks (UMBs)-  Blocks of memory available on some 80x86 based machines
  143.                     which are located between DOS's 640K limit and the
  144.                     1MB address boundary.  The number, size, and location
  145.                     of these blocks vary widely depending upon the types
  146.                     of hardware adapter cards installed in the machine.
  147.  
  148.     Extended Memory
  149.     Blocks (EMBs)-  Blocks of extended memory located above the HMA which
  150.                     can only be used for data storage.
  151.  
  152.     A20 Line    -   The 21st address line of 80x86 CPUs.  Enabling the A20
  153.                     line allows access to the HMA.
  154.  
  155. HIGH MEMORY AREA RESTRICTIONS:
  156. ------------------------------
  157.  
  158. -   Far pointers to data located in the HMA cannot be passed to DOS.  DOS
  159.     normalizes any pointer which is passed into it.  This will cause data
  160.     addresses in the HMA to be invalidated.
  161.  
  162. -   Disk I/O directly into the HMA (via DOS, INT 13h, or otherwise) is not
  163.     recommended.
  164.  
  165. -   Programs, especially drivers and TSRs, which use the HMA *MUST* use
  166.     as much of it as possible.  If a driver or TSR is unable to use at
  167.     least 90% of the available HMA (typically ~58K), they must provide
  168.     a command line switch for overriding HMA usage.  This will allow
  169.     the user to configure his machine for optimum use of the HMA.
  170.  
  171. -   Device drivers and TSRs cannot leave the A20 line permanently turned
  172.     on.  Several applications rely on 1MB memory wrap and will overwrite the
  173.     HMA if the A20 line is left enabled potentially causing a system crash.
  174.  
  175. -   Interrupt vectors must not point into the HMA.  This is a result of
  176.     the previous restriction.  Note that interrupt vectors can point into
  177.     any allocated upper memory blocks however.
  178.  
  179. ERROR CODE INDEX:   ( functions of type UNSIGNED CHAR return these codes )
  180. --------------------------------------------------------------------------
  181.  
  182.     80h if the function is not implemented
  183.     81h if a VDISK device is detected
  184.     82h if an A20 error occurs
  185.     8Eh if a general driver error occurs
  186.     8Fh if an unrecoverable driver error occurs
  187.     90h if the HMA does not exist
  188.     91h if the HMA is already in use
  189.     92h if DX is less than the /HMAMIN= parameter
  190.     93h if the HMA is not allocated
  191.     94h if the A20 line is still enabled
  192.     A0h if all extended memory is allocated
  193.     A1h if all available extended memory handles are in use
  194.     A2h if the handle is invalid
  195.     A3h if the SourceHandle is invalid
  196.     A4h if the SourceOffset is invalid
  197.     A5h if the DestHandle is invalid
  198.     A6h if the DestOffset is invalid
  199.     A7h if the Length is invalid
  200.     A8h if the move has an invalid overlap
  201.     A9h if a parity error occurs
  202.     AAh if the block is not locked
  203.     ABh if the block is locked
  204.     ACh if the block's lock count overflows
  205.     ADh if the lock fails
  206.     B0h if a smaller UMB is available
  207.     B1h if no UMBs are available
  208.     B2h if the UMB segment number is invalid
  209.  
  210. */
  211.